home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / biblio / bibtex / utils / bibclean / README < prev    next >
Text File  |  1992-11-23  |  15KB  |  399 lines
  1. %% /u/sy/beebe/tex/bibclean/README, Tue Nov 24 08:14:30 1992
  2. %% Edit by Nelson H. F. Beebe <beebe@plot79.math.utah.edu>
  3.  
  4. ========================================================================
  5.  
  6. ============
  7. INTRODUCTION
  8. ============
  9.  
  10. This directory contains bibclean, a BibTeX prettyprinter, portability
  11. verifier, and syntax checker.  It can be used to find errors in .bib
  12. files, as well as to standardize their format for readability and
  13. editing convenience.  It can also be used to convert Scribe-format
  14. bibliographies to BibTeX form.
  15.  
  16. Because transfer of binary files between systems is often troublesome,
  17. uuencoded binary executables for IBM PC DOS and DEC VAX VMS are
  18. included in the distribution.  Instructions are given below for
  19. acquiring implementations of uudecode for these systems.
  20.  
  21. The binaries are also present if you got a tar, zip, or zoo
  22. distribution, but are excluded if you got a shar distribution.  If you
  23. do not require either the IBM PC DOS or DEC VAX VMS version, then you
  24. can save about 1.3MB of disk space by deleting the ibmpc and vaxvms
  25. subdirectories.
  26.  
  27. The default pattern matching in bibclean.c is selected by
  28. HAVE_PATTERNS; with it, no regular-expression library support is
  29. needed.  Should you wish to compile with regular-expression support
  30. instead of the HAVE_PATTERNS code, and your system does not have
  31. compile()/step (HAVE_REGEXP), or re_comp()/re_exec() (HAVE_RECOMP),
  32. you may be able to use the regex-?-??.tar.Z distribution from the Free
  33. Software Foundation, available on prep.ai.mit.edu in ~ftp/pub/gnu.
  34.  
  35. In most cases, the HAVE_PATTERNS code is recommended, since it will
  36. give identical results across all machines.  I was prompted to write
  37. it after discovering that there was considerable variety in the
  38. regular expression library codes that resulted in different matching
  39. on different machines, a most unsatisfactory situation.
  40.  
  41. Please report all problems, suggestions, and comments to the author:
  42.  
  43.     Nelson H. F. Beebe
  44.     Center for Scientific Computing
  45.     Department of Mathematics
  46.     University of Utah
  47.     Salt Lake City, UT 84112
  48.     USA
  49.     Tel: +1 801 581 5254
  50.     FAX: +1 801 581 4148
  51.     Email: <beebe@math.utah.edu>
  52.  
  53.  
  54. ============
  55. UNIX Systems
  56. ============
  57.  
  58. The code can be compiled with either C (K&R or ISO/ANSI Standard C) or
  59. C++ compilers; the Makefile contains several different suitable
  60. settings of the CC macro.
  61.  
  62. On UNIX systems, the only changes that you are likely to need in the
  63. Makefile are the settings of CC and CFLAGS, and possibly, DEFINES, and
  64. if you wish to do "make install", the settings of BINDIR, MANDIR, and
  65. MANEXT.
  66.  
  67. If you are installing bibclean on a new system, you should definitely
  68. run "make test" before installing it on your system.  For the target
  69. test-bibtex-2, latex is needed.  For test-bibtex-2 and test-scribe-1,
  70. bibtex is needed.  Sample output of "make test" from a UNIX system
  71. is given below.
  72.  
  73. The code has been tested under several different C and C++ compilers,
  74. and is in regular use to maintain the TeX User Group bibliography
  75. collection stored on math.utah.edu:~ftp/pub/tex/bib, as well as
  76. several other local bibliographies.  These files total more than 200K
  77. lines and 18K bibliography entries.
  78.  
  79. If you port it to a new system, please select maximal error and
  80. warning messages in your compiler.  If you find massive numbers of
  81. errors complaining about function and argument type mismatches, it is
  82. likely that this can be remedied by suitable modifications of os.h.
  83. As C implementations move towards conformance with the December 1989
  84. ISO/ANSI C Language Standard, the C language is a moving target that
  85. must be tracked by os.h.  You can safely ignore complaints about
  86. implicit declaration of library functions; they are caused by
  87. deficiencies in the vendor-provided header files.
  88.  
  89. If you have a C++ compiler, please try that as well.  This code has
  90. been successfully compiled under at least 6 C++ compilers, and the
  91. stricter type checking has uncovered problems that slipped past other
  92. compilers.
  93.  
  94.  
  95. ==========
  96. IBM PC DOS
  97. ==========
  98.  
  99. The ibmpc subdirectory contains these files for the IBM PC:
  100.  
  101.     bibclean.exe        bibclean executable program
  102.     bibclean.uue        uuencoded version of bibclean.exe
  103.     makefile.tcc        Makefile for Turbo C/C++ 3.0
  104.     makefile.msc        Makefile for Microsoft C 5.1, 6.0, 7.0
  105.                 with Microsoft nmake (available in 6.0
  106.                 and 7.0 distributions)
  107.     msc51bld.bat        Build bibclean with Microsoft C 5.1
  108.     msc51pth.bat        Set PATH variable for Microsoft C 5.1
  109.     msc60bld.bat        Build bibclean with Microsoft C 6.0
  110.     msc60pth.bat        Set PATH variable for Microsoft C 6.0
  111.     msc70bld.bat        Build bibclean with Microsoft C 7.0
  112.     msc70pth.bat        Set PATH variable for Microsoft C 7.0
  113.     tcc20bld.bat        Build bibclean with Turbo C 2.0
  114.     tcc20pth.bat        Set PATH variable for Turbo C 2.0
  115.     tcc30bld.bat        Build bibclean with Turbo C++ 3.0
  116.     tcc30pth.bat        Set PATH variable for Turbo C/C++ 3.0
  117.     ibmtest.bat        Test bibclean
  118.  
  119. The executable program has been compiled with Borland Turbo C and C++
  120. 3.0 under MS DOS 4.0 running on a 25MHz Intel 486/DX board in a Sun
  121. SPARCstation 2 with SunPC.  With the 486 board, SunPC provides DOS on
  122. native hardware.  Without it, or under an additional session, it
  123. provides DOS by emulating the Intel instruction set.  bibclean has
  124. also been compiled and successfully tested with Turbo C 2.0, but the C
  125. 3.0 compiled version is the one distributed, because it gives the
  126. smallest bibclean.exe file size:
  127.  
  128.     Turbo C 2.0:    55844
  129.     Turbo C 3.0:    53936
  130.     Turbo C++ 3.0:    97874
  131.  
  132. [The distribution size may be slightly different; the given sizes are
  133. a snapshot near the end of the 2.05 development.]
  134.  
  135. bibclean has also been successfully built with Microsoft C 5.1 and
  136. 6.0.  Version 5.0 has fatal compiler errors that prevent its use for
  137. this program; I could not find acceptable code workarounds.  I have
  138. been unable to run version 7.0 on my SPARCstation; the compiler dies
  139. with a "runtime error R6018 - unexpected heap error", despite my
  140. having installed the Qualitas 386MAX memory manager that comes with
  141. Microsoft C 7.0.  Thus, although there are .bat files and makefile.msc
  142. for 7.0, they have not been tested, and regrettably, 7.0 C++ cannot be
  143. used.  Each C++ compiler I've tried has exposed new things that need
  144. fixing.  I tried unsuccessfully to install Microsoft C 7.0 on our lab
  145. PCs, but that too failed, because 7.0 needs a 386 with more than 4MB
  146. of memory, and our PCs are old 286 models, sigh...
  147.  
  148. The bibclean executable sizes from Microsoft C are larger than with
  149. Turbo C, so I'm not distributing them:
  150.  
  151.     Microsoft C 5.1:    98601
  152.     Microsoft C 6.0:    92499
  153.  
  154. The Microsoft port gave considerable trouble, because I was unable to
  155. get the stack and data segments to be separated, despite using teh
  156. compiler option (-Asfu) to do so.  Compilation would complete
  157. normally, then the linker would complain that stack + data exceeded
  158. 64KB.  Since the Turbo C build had been successful in the compact
  159. memory model, I did not want to go to the large model for Microsoft C.
  160. I finally succeeded by using the -Gt1024 option, which forces objects
  161. larger than 1024 bytes to be placed in a separate section.  This left
  162. room for a stack size of 0xb000 (45056 bytes), which is more than
  163. ample.
  164.  
  165. A few small code codes changes were needed for the Microsoft C
  166. compilers.  In particular, it would not accept const modifiers in
  167. certain (legal) places.  The workaround is to rewrite them as a macro
  168. CONST which expands to an empty string with M_I86 is defined (the only
  169. symbol that appears to uniquely differentiate between C compilers from
  170. Borland, Microsoft, and TopSpeed), and to const otherwise.
  171.  
  172. Since bibclean uses no floating-point arithmetic, and PC DOS has no
  173. shared libraries, I expect that the executable will run on any version
  174. of DOS greater than 4.0.  It may also run on earlier versions.  At the
  175. time of writing 5.0 is current, and this bibclean executable works
  176. fine on it.
  177.  
  178. To rebuild bibclean, you will need to adjust directory paths in
  179. makefile.msc, makefile.tcc, msc*.bat and/or tcc*.bat.  The *bld.bat
  180. files can be used to build bibclean, or if you have Turbo C/C++ 3.0,
  181. you can copy makefile.tcc to makefile and type "make".  With Microsoft
  182. C 5.1 and the 6.0 nmake utility, you can copy makefile.msc to makefile
  183. and do "nmake".  The Microsoft 6.0 compiler is too big to run
  184. underneath nmake; the workaround is fortunately simple:
  185.  
  186.     nmake -n >foo.bat
  187.     foo
  188.  
  189. You should definitely run ibmtest to make sure the newly-built program
  190. is working correctly; you'll need to copy bibclean.exe and ibmtest.bat
  191. into the top-level bibclean directory in order for it to find the test
  192. files.  Unlike the UNIX "make test", ibmtest does not require that
  193. latex or bibtex be installed on your system.
  194.  
  195. If you don't have uuencode/uudecode for IBM PC DOS, you can get it via
  196. e-mail; for details, send a message with the lines
  197.  
  198.     help
  199.     send index from support
  200.     send index from ftp/ibmpc
  201.     send uuarc.arc from ftp/ibmpc
  202.     send uuencode.arc from ftp/ibmpc
  203.  
  204. to tuglib@math.utah.edu.  Alternatively, you can use anonymous ftp to
  205. ftp.math.utah.edu and fetch the files uuarc.arc or uuencode.arc from
  206. ~ftp/pub/ibmpc.  uuarc.arc contains only .com executables;
  207. uuencode.arc contains sources, makefiles, and .exe files.
  208.  
  209. If your transfer of these files did not translate UNIX LF line
  210. terminators to PC DOS CR LF terminators, the ux2dos and dos2ux
  211. utilities can be of assistance.  You can find their source code in
  212. ~ftp/pub/ibmpc/dos2ux.shar (via e-mail to tuglib@math.utah.edu, "send
  213. dos2ux.shar from support".
  214.  
  215.  
  216. ===========
  217. DEC VAX VMS
  218. ===========
  219.  
  220. The vaxvms subdirectory contains these files for DEC VAX VMS:
  221.  
  222.     bibclean.exe        bibclean executable program
  223.     bibclean.uue        uuencoded version of bibclean.exe
  224.     recomp.com        do @recomp foo to recompile foo.c
  225.     vmsclean.com        do @vmsclean to cleanup after a build
  226.     vmsmake.com        do @vmsmake to build bibclean
  227.     vmstest.com        do @vmstest to test bibclean
  228.  
  229. You will have to change one line in vmstest.com to define the disk
  230. location of bibclean.exe in the foreign command symbol for bibclean.
  231. If you don't have uuencode/uudecode for VAX VMS, you can get it via
  232. e-mail; for details, send a message with the lines
  233.  
  234.     help
  235.     send index from support
  236.  
  237. to tuglib@math.utah.edu.
  238.  
  239. Unlike the UNIX "make test", execution of vmstest.com does not require
  240. that latex or bibtex be installed on your system.  [I didn't have
  241. either on the VAX VMS system that I built bibclean on.]
  242.  
  243.  
  244. ==================================
  245. SAMPLE "make test" OUTPUT FOR UNIX
  246. ==================================
  247.  
  248. ==================== begin BibTeX test 1 =====================
  249.  
  250.  
  251. ./bibclean -init-file bibclean.ini testbib1.org >testbib1.bib 2>testbib1.err
  252.  
  253. There should be no differences found:
  254. diff testbib1.bok testbib1.bib
  255.  
  256. There should be no differences found:
  257. diff testbib1.eok testbib1.err
  258.  
  259. ===================== end BibTeX test 1 ======================
  260.  
  261.  
  262. ==================== begin BibTeX test 2 =====================
  263.  
  264.  
  265. ./bibclean -init-file bibclean.ini -no-check-values testbib2.org >testbib2.bib 2>testbib2.err
  266.  
  267. There should be no differences found:
  268. diff testbib2.bok testbib2.bib
  269.  
  270. There should be no differences found:
  271. diff testbib2.eok testbib2.err
  272.  
  273. latex testbib2.ltx >/dev/null
  274.  
  275. Expect 6 BibTeX warnings:
  276. bibtex testbib2
  277. This is BibTeX, C Version 0.99c
  278. The top-level auxiliary file: testbib2.aux
  279. The style file: alpha.bst
  280. Database file #1: testbib2.bib
  281. Warning--empty year in Bennett
  282. Warning--empty year in Cejchan
  283. Warning--there's a number but no volume in Dubowsky:75
  284. Warning--empty institution in Diver:88a
  285. Warning--empty booktitle in Diver:88
  286. Warning--empty year in Diver
  287. (There were 6 warnings)
  288.  
  289. latex testbib2.ltx >/dev/null
  290.  
  291. latex testbib2.ltx
  292. This is TeX, C Version 3.14t3
  293. (testbib2.ltx
  294. LaTeX Version 2.09 <7 Dec 1989>
  295. (/usr/local/lib/tex/inputs/article.sty
  296. Document Style `article' <16 Mar 88>.
  297. (/usr/local/lib/tex/inputs/art10.sty)) (testbib2.aux) (testbib2.bbl [1]
  298. [2] [3]
  299. Underfull \hbox (badness 1024) in paragraph at lines 261--264
  300. [] []\tenrm L. M. Berkovich, V. P. Gerdt, Z. T. Kos-tova, and M. L.
  301. [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16]) [17] (testbib2.aux)
  302.  )
  303. (see the transcript file for additional information)
  304. Output written on testbib2.dvi (17 pages, 49032 bytes).
  305. Transcript written on testbib2.log.
  306.  
  307. ===================== end BibTeX test 2 ======================
  308.  
  309.  
  310. ==================== begin BibTeX test 3 =====================
  311.  
  312. ./bibclean -init-file bibclean.ini testisxn.org >testisxn.bib 2>testisxn.err
  313. *** Error code 1 (ignored)
  314.  
  315. There should be no differences found:
  316. diff testisxn.bok testisxn.bib
  317.  
  318. There should be no differences found:
  319. diff testisxn.eok testisxn.err
  320.  
  321. ===================== end BibTeX test 3 ======================
  322.  
  323.  
  324. ==================== begin Scribe test 1 =====================
  325.  
  326.  
  327. ----------------------------------------------------
  328.  
  329. ./bibclean -init-file bibclean.ini -scribe -no-check testscr1.org >testscr1.bib
  330.  
  331. There should be no differences found:
  332. diff testscr1.bok testscr1.bib
  333.  
  334. There should be no differences found:
  335. diff testscr1.eok testscr1.err
  336.  
  337. Expect 5 BibTeX warnings
  338. bibtex testscr1
  339. This is BibTeX, C Version 0.99c
  340. The top-level auxiliary file: testscr1.aux
  341. The style file: plain.bst
  342. Database file #1: testscr1.bib
  343. Warning--empty publisher in hanson-67
  344. Warning--can't use both volume and number fields in kendeigh-52
  345. Warning--empty author in singer-portion-chapter
  346. Warning--empty author in singer-portion-volume
  347. Warning--can't use both author and editor fields in wright-63
  348. (There were 5 warnings)
  349.  
  350. ----------------------------------------------------
  351.  
  352. ./bibclean -init-file bibclean.ini -scribe -no-check testscr2.org >testscr2.bib
  353.  
  354. There should be no differences found:
  355. diff testscr2.bok testscr2.bib
  356.  
  357. There should be no differences found:
  358. diff testscr2.eok testscr2.err
  359.  
  360. There should be no BibTeX warnings:
  361. bibtex testscr2
  362. This is BibTeX, C Version 0.99c
  363. The top-level auxiliary file: testscr2.aux
  364. The style file: plain.bst
  365. Database file #1: testscr2.bib
  366. ===================== end Scribe test 1 ======================
  367.  
  368.  
  369. ==================== begin Scribe test 2 =====================
  370.  
  371. ./bibclean -init-file bibclean.ini -scribe -file -no-check -no-par testscr2.org \
  372.     >testscr2.bi2 2>testscr2.er2
  373. *** Error code 1 (ignored)
  374.  
  375. There should be no differences found:
  376. diff testscr2.bo2 testscr2.bi2
  377.  
  378. There should be no differences found:
  379. diff testscr2.eo2 testscr2.er2
  380.  
  381. ===================== end Scribe test 2 ======================
  382.  
  383.  
  384. ==================== begin Scribe test 3 =====================
  385.  
  386. ./bibclean -init-file bibclean.ini -scribe -no-check testscr3.org >testscr3.bib 2>testscr3.err
  387.  
  388. There should be no differences found:
  389. diff testscr3.bok testscr3.bib
  390.  
  391. There should be no differences found:
  392. diff testscr3.eok testscr3.err
  393.  
  394. ===================== end Scribe test 3 ======================
  395.  
  396.  
  397.  
  398. ===============================[The End]===============================
  399.